<pre class='metadata'>
Title: Selectors Level 5
Group: CSSWG
Shortname: selectors
Level: 5
Status: ED
!Delta Spec: yes
Work Status: Exploring
ED: https://drafts.csswg.org/selectors-5/
TR: https://www.w3.org/TR/selectors-5/
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Abstract: <a>Selectors</a> are patterns that match against elements in a tree, and as such form one of several technologies that can be used to select nodes in a document. Selectors have been optimized for use with HTML and XML, and are designed to be usable in performance-critical code. They are a core component of <abbr title="Cascading Style Sheets">CSS</abbr> (Cascading Style Sheets), which uses Selectors to bind style properties to elements in the document.
Abstract: Selectors Level 5 describes the selectors that already exist in [[!selectors-4]], and further introduces new selectors for CSS and other languages that may need them.
WPT Path Prefix: css/selectors/
WPT Display: closed
</pre>

<pre class="link-defaults">
spec:selectors-4; type:dfn; text:selector
spec:html; type:dfn; text:states set
spec:html; type:dfn; text:heading level
</pre>

<h2 id="intro">
Introduction</h2>

	ISSUE: <strong>This is a diff spec against
	<a href="https://www.w3.org/TR/selectors-4/">Selectors Level 4</a>.</strong>

<h3 id="placement">
Module Interactions</h3>

	This module extends
	the set of selectors defined for CSS in [[selectors-4]].

<h2 id="location">
Location Pseudo-classes</h2>

<h3 id="local-pseudo">
The local link pseudo-class '':local-link''</h3>

	The <dfn id='local-link-pseudo'>:local-link</dfn> pseudo-class allows authors to style
	[[selectors-4#the-any-link-pseudo|hyperlinks]]
	based on the users current location within a site and to
	differentiate site-internal versus site-external links.

	The (non-functional) '':local-link'' pseudo-class represents an element that is
	the source anchor of a hyperlink whose target's absolute URL
	matches the element's own document URL.
	Any fragment identifiers are stripped before matching the document's URL against the link's URL;
	otherwise all portions of the URL are considered.

	<div class="example">
		For example, the following rule prevents links targeting the
		current page from being underlined when they are part of the
		navigation list:

		<pre>nav :local-link { text-decoration: none; } </pre>
	</div>

	As a functional pseudo-class,
	'':local-link()'' can also accept a non-negative integer as its sole argument,
	which, if the document's URL belongs to a hierarchical scheme,
	indicates the number of path levels to match:

	<ul>
		<li>'':local-link(0)'' represents a link element whose target is in the same origin as the document's URL
		<li>'':local-link(1)'' represents a link element whose target has the same origin and first path segment
		<li>'':local-link(2)'' represents a link element whose target has the same origin, first, and second path segments
		<li>etc.
	</ul>

	<div class="example">
		The following example styles all site-external links with a dashed
			underline.

		<pre>:not(:local-link(0)) { text-decoration-style: dashed; } </pre>
	</div>

	Path segments are portions of the URL's path that are separated by forward slashes (/).
	If a segment is missing from the document's URL,
	a pseudo-class requiring that segment to match does not match anything.

	<div class="example">
		So, given the links:

		<ol>
			<li><code>&lt;a href="http://www.example.com">Home&lt;/a></code>
			<li><code>&lt;a href="http://www.example.com/2011">2011&lt;/a></code>
			<li><code>&lt;a href="http://www.example.com/2011/03">March&lt;/a></code>
			<li><code>&lt;a href="http://www.example.com/2011/03/">March&lt;/a></code>
			<li><code>&lt;a href="http://www.example.com/2011/03/21">21 March&lt;/a></code>
			<li><code>&lt;a href="https://www.example.com/2011/03/">March&lt;/a></code>
			<li><code>&lt;a href="http://example.com/2011/03/">March&lt;/a></code>
		</ol>

		and the styles:

		<ol type=A>
			 <li><code>a:local-link {...}</code>
			 <li><code>a:local-link(0) {...}</code>
			 <li><code>a:local-link(1) {...}</code>
			 <li><code>a:local-link(2) {...}</code>
			 <li><code>a:local-link(3) {...}</code>
			 <li><code>a:local-link(4) {...}</code>
		</ol>

		If the document's URL is <code>http://www.example.com/2011/03/</code>:

		<ol>
			<li>Link 1 would receive Style B
			<li>Link 2 would receive Styles B and C
			<li>Link 3 would receive Styles B, C, and D
			<li>Link 4 would also receive Styles A, B, C, D, and E
			<li>Link 5 would receive Styles B, C, and D
			<li>Link 6 would remain unstyled
			<li>Link 7 would remain unstyled
			<li>Style F would not be applied to anything
		</ol>
	</div>


		The "origin" of the URL is defined by <a href="http://tools.ietf.org/html/rfc6454#section-4">RFC 6454, Section 4</a>.
		The username, password, query string, and fragment portions of the URL are not considered
		when matching against '':local-link(<var ignore>n</var>)''.
		If the document's URL does not belong to a hierarchical scheme,
		the functional pseudo-class matches nothing.

	<p class="issue">
		It's clear that, if the document URL has at least N segments,
		then '':local-link(N)'' only matches links whose URL has at least N segments.
		(This lets you assign consistent semantics to :local-link so that,
		for example, :local-link(2) means a "within-repo" link on GitHub.)
		What about if the document url has less than N segments,
		and the link is same-page?
		Should "null segments" count as matching, or not?

<h2 id="custom-state">
Exposing custom state: the '':state()'' pseudo-class</h2>

	The <dfn selector id="state-pseudo">:state( <<ident>> )</dfn> pseudo-class
	matches [=custom elements=]
	whose [=states set=] contains a string
	that [=string/is=] the selector's argument's value.

	<wpt>
		parsing/parse-state.html
	</wpt>

	<!-- Using <<ident>>, rather than <<custom-ident>>,
	     to avoid excluding the CSS-wide keywords. -->

	Note: The "[=string/is=]" matching behavior compares strings by codepoint;
	notably, it's case-sensitive.
	So if "foo" is in the [=states set=], '':state(FOO)'' will <em>not</em> match.

	The exact matching behavior of '':state()'' pseudo-class
	is defined by the host language.
	For clarity, the concepts explaining this pseudo-class
	link to the HTML definition;
	see <a href="https://html.spec.whatwg.org/multipage/custom-elements.html#custom-state-pseudo-class">HTML's definition</a> for more detail.
	Other host languages must define how this pseudo-class matches.

<h2 id="headings">
Heading Structures: the heading pseudo-classes '':heading'', and '':heading()''</h2>

	The (non-functional) <dfn id='heading-pseudo'>:heading</dfn> pseudo-class
	matches an element which has a <a>heading level</a>, with respect to the
	semantics defined by the document language (e.g. [[HTML5]]).

	The [=specificity=] of '':heading'' is that of a class.

	<div class="example">
		For example, the following sheet contains a rule applying to all heading
		elements in the current page:

		<pre>:heading { text-decoration: underline; }</pre>
	</div>

	As a functional pseudo-class,
	<dfn id='heading-functional-pseudo' lt=':heading()'>:heading()</dfn>
	notation represents elements that have a <a>heading level</a> among matching
	any of the provided <var>integer</var> values.
	The syntax is:

	<pre class=prod>
		:heading() = :heading( <<level>># )
	</pre>

	where <dfn><code>&lt;level></code></dfn> is a <<number-token>> with its type flag set to "integer".

	The [=specificity=] of '':heading()'' is that of a class.

	<div class="example">
		The following example styles headings with levels between 1 and 3 with a
		font-weight of 900, while headings with levels 6 onward with font-weight of
		500, additionally heading levels 1 and 2 will be underlined, while 3 and
		beyond will have no text-decoration:

		<pre>:heading(1, 2, 3) { font-weight: 900; }</pre>
		<pre>:heading(6, 7, 8, 9) { font-weight: 500; }</pre>
		<pre>:heading(1, 2) { text-decoration: underline; }</pre>
		<pre>:heading(3, 4, 5, 6, 7, 8, 9) { text-decoration: none; }</pre>
	</div>

	Note: The <a>heading level</a> might be different from an element's
	<a>type selector</a>. Thus, a selector ''h1:heading(3)'' matches any
	''h1'' tag which has an exposed heading level of 3.

	<wpt>
		heading.html
		parsing/parse-heading.html
	</wpt>

<h2 id="combinators">
Combinators</h2>

<h3 id="idref-combinators">
Reference combinators <code>/ref/</code></h3>

	The <dfn export>reference combinator</dfn> consists of two slashes
	with an intervening <a href="http://www.w3.org/TR/css3-namespace/#css-qnames">CSS qualified name</a>,
	and separates two <a>compound selectors</a>,
	e.g. ''A /attr/ B''.
	The element represented by the first <a>compound selector</a>
	explicitly references
	the element represented by the second <a>compound selector</a>.
	Unless the host language defines a different syntax for expressing this relationship,
	this relationship is considered to exist if
	the value of the specified attribute on the first element is an IDREF or an <a>ID selector</a>
	referencing the second element.

	Attribute matching for reference combinators follow the same rules as for <a href="http://www.w3.org/TR/css3-selectors/#attribute-selectors">attribute selectors</a>.

	<div class="example">
		The following example highlights an <a element>input</a> element
		when its <a href="http://www.w3.org/TR/html40/interact/forms.html#h-17.9"><code>&lt;label></code></a>
		is focused or hovered-over:

		<pre>
		label:is(:hover, :focus) /for/ input,       /* association by "for" attribute */
		label:is(:hover, :focus):not([for]) input { /* association by containment */
			box-shadow: yellow 0 0 10px;
		}
		</pre>
	</div>


<h2 id="changes">
Changes</h2>

<h3 id="changes-level-4">
Changes Since Level 4</h3>

	Additions since <a href="https://www.w3.org/TR/selectors-4/">Level 4</a>:

	<ul>
	        <li>Reference combinators
	        (deferred from an <a href="https://www.w3.org/TR/2013/WD-selectors4-20130502/">earlier draft</a> of Selectors 4)</li>
	        <li>The functional form of the '':local-link'' pseudo-class
	        (deferred from an <a href="https://www.w3.org/TR/2013/WD-selectors4-20130502/">earlier draft</a> of Selectors 4)</li>
	        <li>The '':state()'' pseudo-class</li>
	        <li>The '':heading'' and '':heading()'' pseudo-classes</li>
	</ul>

<h2 id="acknowledgements">
Acknowledgements</h2>

	The CSS working group would like to thank everyone who contributed
	to the <a href="https://www.w3.org/TR/selectors-4">previous Selectors</a> specifications over the years,
	as those specifications formed the basis for this one.
	In particular, the working group would like to extend special thanks
	to the following for their specific contributions to Selectors Level 5:
	Joey Arhar.

	<h2 class=no-num id=privacy>Privacy Considerations</h2>

	<p>Should be copied from Level 4 when appropriate.</p>

	<h2 class=no-num id=security>Security Considerations</h2>

	<p>Should be copied from Level 4 when appropriate.</p>


